Skip to content

Integrate GitHub README as Sphinx landing page with custom extension - #412

Open
jpjarnoux wants to merge 8 commits into
labgem:devfrom
jpjarnoux:docs/readme_duplicate
Open

jpjarnoux wants to merge 8 commits into
labgem:devfrom
jpjarnoux:docs/readme_duplicate

Conversation

@jpjarnoux

@jpjarnoux jpjarnoux commented Oct 7, 2026 •

Copy link
Copy Markdown
Member

Description

README and index documentation page are duplicated, but GitHub format and Sphinx format are not fully compatible. In this PR I intend to remove duplicating file by writing a custom script called in the documentation building.

What changed

  • Added a custom Sphinx extension github_readme to parse GitHub README syntax into MyST format.
  • Updated documentation to use GitHub-flavored Markdown features (colon_fence, linkify, tasklist, etc.).
  • Modified README.md to incorporate GitHub alert syntax.
  • Added unit tests for README parsing and custom extension validation.
  • Updated pyproject.toml to include linkify-it-py dependency.

Testing

A new unitary script works as a first cheap barrier. It's fast and doesn't need Sphinx or the test dataset. If someone adds MyST syntax to the README, CI fails and shows the line, before it reaches GitHub.

Rendering was tested both locally and directly into ReadTheDocs.

Additional note

This PR is based on the same change done in PANORAMA labgem/PANORAMA#64

@jpjarnoux
jpjarnoux changed the base branch from master to dev October 7, 2026 12:15
@jpjarnoux
jpjarnoux requested a review from JeanMainguy October 7, 2026 12:20
@jpjarnoux jpjarnoux changed the title Docs/readme duplicate Integrate GitHub README as Sphinx landing page with custom extension Oct 7, 2026
@jpjarnoux
jpjarnoux marked this pull request as ready for review October 7, 2026 12:20
@JeanMainguy

Copy link
Copy Markdown
Member

The ppanggolin logo was not showing up correctly in the doc. I had to modify slightly the docs/_ext/github_readme.py script.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants